入门实战：基于 MxCAD 与 MxDraw 构建 Web CAD 预览与批注应用

0. 前言

在之前的文档中，我们已对 MxCAD 产品进行了宏观介绍，并完成了开发环境的初步搭建与 Demo 运行。然而，从“运行官方示例”到“构建自有业务系统”之间，仍存在概念理解与工程落地的鸿沟。

本篇文档的核心目标在于填补这一空白，重点解决以下两个关键问题：

概念理清：深入解析 MxCAD 与 MxDraw 的技术定位与职能边界。明确 MxCAD 作为“编辑内核”负责原图数据的深度操作，而 MxDraw 作为“渲染引擎”专注于图纸浏览与非侵入式批注。
工程落地：指导开发者在自己的项目中，从零构建一个具备图纸加载、视图浏览、独立批注功能的最小可行性产品（MVP），下面以vue项目为讲解示例。

通过本文的学习，您将掌握如何根据业务需求（是仅需审阅批注，还是需要修改原图）选择合适的技术组件，并能够独立搭建起一个可运行的 Web CAD 基础框架，为后续开发复杂的在线设计平台奠定坚实基础。

1. 核心架构解析：MxCAD 与 MxDraw 的功能界定

在梦想云图（DreamCloud CAD）的技术体系中，MxCAD 与 MxDraw 是两个核心组件。尽管二者在底层紧密耦合，但在业务逻辑与应用场景上存在明确的职能划分。理解二者的区别是进行二次开发的前提。

1.1 MxDraw：轻量级前端渲染与批注引擎

定义：MxDraw 是一个基于 HTML5 Canvas 及 WebGL 技术的前端图形渲染引擎。
核心职能：图纸浏览与非侵入式批注。
- 渲染展示：负责将 CAD 矢量数据高效地绘制于浏览器端，支持平移、缩放、旋转等视图操作。
- 批注处理：提供独立的批注图层管理功能。用户可在图纸上层添加云线、文字注释、测量标记等信息。
- 数据隔离：MxDraw 的批注操作不修改原始 DWG/DXF 文件的几何数据与数据库结构。批注信息通常以独立文件（如 JSON 或专用批注格式）存储，或与原图分离保存，确保原图的完整性与安全性。
适用场景：图纸在线审阅、协同设计标注、移动端轻量化查看、无需修改原图的设计评审。

1.2 MxCAD：全功能 CAD 业务内核

定义：MxCAD 是基于 C++ 核心通过 WebAssembly (Wasm) 移植至 Web 端的专业 CAD 开发框架。
核心职能：图纸数据编辑与深度业务逻辑。
- 数据解析：完整解析 AutoCAD 原生格式（DWG/DXF），支持所有版本及复杂实体。
- 实体编辑：提供对图纸底层数据库的直接读写能力。支持实体的创建、修改、删除、属性变更等操作，这些操作会直接改变原图纸的数据结构。
适用场景：Web 端在线绘图、图纸深化设计、自动化生成报表、基于图纸数据的业务系统集成。

1.3 协作机制与版本演进

在实际的技术架构中，MxCAD 与 MxDraw 并非孤立存在，而是呈现出紧密的层级协作与演进关系：

基础与升级的关系

MxDraw 是梦想云图技术体系的基础层。它提供了核心的 HTML5 Canvas 渲染能力、基础的图形交互逻辑以及轻量级的批注功能。其设计初衷是解决“在网页上快速、高效地展示和标注 CAD 图纸”这一核心痛点。
MxCAD 则是基于 MxDraw 的全功能升级版本。它在保留并复用 MxDraw 所有渲染与交互优势的基础上，通过引入 C++ 内核（编译为 WebAssembly）和 TypeScript 业务框架，扩展了完整的 CAD 数据解析、实体编辑、几何计算及复杂命令处理能力。
简而言之：MxCAD = MxDraw (渲染与交互) + CAD 专业内核 (数据与逻辑)。

协作模式

默认集成：在大多数应用场景下，开发者引入 MxCAD 开发包时，实际上已经包含了 MxDraw 的功能模块。MxCAD 内部会自动调用 MxDraw 进行图形绘制和用户交互监听。
按需调用：
- 若业务场景仅需查看与批注（如图纸审阅、移动端巡查），可直接利用 MxCAD 中集成的 MxDraw 接口模式。此时系统表现为轻量级引擎，不加载重型编辑内核（或仅使用其渲染部分），确保启动速度与运行性能。
- 若业务场景涉及原图修改、参数化设计或数据提取，则激活 MxCAD 的完整内核功能，对底层数据库进行读写操作。
无缝切换：由于二者同源，开发者可以在同一个项目中根据权限或功能模块，动态切换“只读/批注模式”与“编辑模式”，无需更换底层引擎，保证了用户体验的一致性与技术架构的统一性。

这种架构设计既保证了轻量级应用的极致性能，又为专业级应用提供了无限扩展的可能。

2. 构建基础 CAD 项目：图纸预览与批注实战

2.1 环境准备与项目初始化

1. 环境要求

Node.js: ≥ v16
包管理器: npm / pnpm
构建工具:
- Vite (推荐，配置简单，开发速度快)
- Webpack (支持，需配置 worker-loader 或相关 WASM 处理规则)
- 其他：Rollup, Parcel 等支持自定义 Loader/Plugin 的构建工具均可。
后端服务: 需运行云图开发包提供的图纸转换服务，用于处理 DWG/DXF 转 MXWEB。
- 可直接开启云图开发包 3000 端口下的服务。
- 也可自行根据图纸转换文档规则设置新的转换接口。

2. 创建或集成项目

您可新建项目或在现有项目中添加 CAD 模块：

bash

# 新建 Vue3 + TypeScript 项目
npm create vite@latest cad-viewer -- --template vue-ts
cd cad-viewer
npm install

3. 安装核心依赖

bash

# 安装 mxcad 核心包
npm install mxcad

# 若使用 pnpm，请额外安装 mxdraw (通常 mxcad 已包含，视具体版本策略而定)
# pnpm add mxdraw

4. 配置构建工具支持多线程

MxCAD 的高性能渲染依赖 SharedArrayBuffer，这要求服务器响应头必须包含 Cross-Origin-Opener-Policy: same-origin 和 Cross-Origin-Embedder-Policy: require-corp。无论使用何种打包工具（Webpack、Rollup 等），都必须进行此配置，否则引擎将无法启动或自动降级。

以下以 Vite 为例演示配置方法：

修改 vite.config.ts，在 server.headers 中添加响应头：

typescript

// vite.config.ts
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'

export default defineConfig({
  plugins: [vue()],
  server: {
    // 开发环境：直接在此处配置响应头
    headers: {
      "Cross-Origin-Opener-Policy": "same-origin",
      "Cross-Origin-Embedder-Policy": "require-corp",
    }
  },
  build: {
    target: 'esnext' // 确保编译目标支持最新特性
  }
})

2.2 创建 Canvas 容器与初始化 MxCAD 引擎

1. 模板结构：Canvas 与文件上传控件

在组件模板中定义渲染容器和文件选择器，并添加控制按钮。

html

<template>
  <!-- CAD 渲染区域 -->
  <div style="width: 100vw; height: 95vh; overflow: hidden;">
    <canvas id="myCanvas"></canvas>
  </div>

  <!-- 控制栏 -->
  <div style="margin-top: 10px; padding: 10px; background: #f5f5f5;">
    <!-- 隐藏的文件输入框 -->
    <input
      type="file"
      ref="fileInput"
      accept=".dwg,.dxf,.mxweb"
      @change="openDwgFile"
      style="display:none"
    />
    
    <!-- 功能按钮 -->
    <button @click="$refs.fileInput.click()" :disabled="!mxcadReady">打开图纸</button>
    <button @click="startCloudMark" :disabled="!mxcadReady">绘制云线批注</button>
    <button @click="saveMarkup" :disabled="!mxcadReady">保存批注</button>
    <button @click="loadMarkup" :disabled="!mxcadReady">加载批注</button>
  </div>
</template>

2. 初始化 MxCAD 实例

在 Vue 组件的 onMounted 生命周期中调用 createMxCad，完成 Canvas 绑定、WASM 核心文件路径定位、字体库路径设置以及初始化完成的回调处理。

vue

<script setup lang="ts">
import { onMounted, ref } from 'vue';
import { createMxCad, MxCpp } from 'mxcad';

const mxcadReady = ref(false);
const fileInput = ref<HTMLInputElement | null>(null);

onMounted(() => {
  // 自动检测浏览器环境：支持 SharedArrayBuffer 则启用多线程 (2d)，否则降级为单线程 (2d-st)
  const mode = "SharedArrayBuffer" in window ? "2d" : "2d-st";

  createMxCad({
    canvas: "#myCanvas",
    // 动态定位 WASM 文件路径，兼容 Vite/Webpack 等构建工具
    locateFile: (fileName: string) => {
      return new URL(
        `../../node_modules/mxcad/dist/wasm/${mode}/${fileName}`,
        import.meta.url
      ).href;
    },
    fileUrl: "", // 初始不加载文件，等待用户通过 UI 选择
    fontspath: new URL(
      "../../node_modules/mxcad/dist/fonts",
      import.meta.url
    ).href,
    // 初始化完成回调
    onInit: () => {
      console.log("MxCAD 引擎初始化完成");
      mxcadReady.value = true;
    }
  });
});
</script>

更多配置项： createMxCad 支持丰富的自定义配置（如背景色、多选配置、视区移动方式等）。如需了解完整的配置参数列表及详细说明，请访问官方文档：[MxCadConfig 配置接口文档。

2.3 打开图纸并预览（关键格式说明）

重要说明：MxCAD 文件格式限制
MxCAD 引擎内核仅能直接解析和打开特定的 .mxweb 格式文件。它无法直接在浏览器端读取原生的 AutoCAD 格式（如 .dwg 或 .dxf）。
因此，在实现“打开图纸”功能时，必须遵循以下逻辑：
判断格式：检查用户选择的文件后缀。
格式转换：如果文件是 .dwg 或 .dxf，必须先将其上传至后端转换服务，由服务端将其转换为 .mxweb 格式。
加载渲染：只有获取到 .mxweb 格式的文件流或 URL 后，才能调用 mxcad.openWebFile() 进行加载和渲染。
若跳过转换步骤直接尝试加载 DWG 文件，MxCAD 将报错或无法显示任何内容。

1. 文件选择与处理流程

基于上述限制，我们的代码逻辑分为两条路径：

路径 A (.mxweb)：浏览器原生支持，直接生成临时 URL 加载。
路径 B (.dwg/.dxf)：调用本地转换服务 localhost:3000/uploadfile 上传 -> 服务端自动转换 -> 返回/生成 .mxweb 路径 -> 加载。

2. 跨域处理配置

由于前端开发服务器（默认 localhost:5173）与图纸转换服务（localhost:3000）端口不同，直接请求会触发浏览器的跨域限制 (CORS)。

无论使用何种打包工具（Webpack、Rollup 等），在开发环境下都必须配置代理（Proxy）或将请求转发至同源，以解决跨域问题。生产环境通常通过 Nginx 反向代理统一入口来解决。

以下以 Vite 为例演示开发环境的代理配置：

修改 vite.config.ts，添加 server.proxy 配置，将 /api 或特定路径的请求转发至转换服务：

typescript

// vite.config.ts
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'

export default defineConfig({
  plugins: [vue()],
  server: {
    // ....其他配置
      
    // 开发环境跨域代理配置
    proxy: {
      // 匹配所有以 /api 开头的请求（建议前端请求时加上 /api 前缀）
      '/api': {
        target: 'http://localhost:3000', // 图纸转换服务地址
        changeOrigin: true,              // 修改 Host 头为 target
        rewrite: (path) => path.replace(/^\/api/, ''), // 去掉 /api 前缀再转发
      },
      // 或者直接代理特定的转换接口路径
      //'/uploadfile': {
      //  target: 'http://localhost:3000',
      //  changeOrigin: true,
      // },
      // '/demo': {
      //  target: 'http://localhost:3000',
      //  changeOrigin: true,
      // }
    }
  }
})

前端代码适配示例： 配置代理后，前端请求地址需调整为相对路径或带前缀的路径：

typescript

// 原地址：http://localhost:3000/uploadfile
// 代理后地址：/api/uploadfile (需在 proxy 中配置 rewrite) 或直接 /uploadfile
const res = await fetch("/api/uploadfile", { // Vite 会自动拦截并转发到 localhost:3000/uploadfile
  method: "POST",
  body: formData,
});

3. 代码实现：打开网络图纸

图纸的加载与渲染核心依赖于 MxCAD 提供的 openWebFile API。该接口支持从网络 URL 直接加载 .mxweb 或转换后的图纸数据，并提供了丰富的参数控制（如是否使用多线程、加载策略等）。

typescript

<script setup lang="ts">
// ... 上述初始化代码 ...

// 打开图纸处理函数
const openDwgFile = async (event: Event) => {
  const target = event.target as HTMLInputElement;
  const file = target.files?.[0];
  
  if (!file) return;
  
  const fileName = file.name;
  // 获取文件后缀并转为小写
  const fileExt = fileName.slice(fileName.lastIndexOf(".")).toLowerCase();
  const mxcad = MxCpp.getCurrentMxCAD();

  if (fileExt === ".dwg" || fileExt === ".dxf") {
    // DWG/DXF 需要后端转换
    const formData = new FormData();
    formData.append("file", file);
    
    try {
      // 调用代理后的上传接口
      const res = await fetch("/upfile/mxcad", {
        method: "POST",
        body: formData,
      });
      
      if (!res.ok) throw new Error(`请求失败：${res.status}`);
      
      // 约定：转换后的文件位于 /demo/ 目录下，文件名不变，后缀变为 .mxweb
      const mxwebFullUrl = `/demo/${fileName}.mxweb`;
      mxcad.openWebFile(mxwebFullUrl);
      
    } catch (err) {
      console.error(err);
      alert("上传或转换失败，请检查后端服务是否启动");
    }
  } else if (fileExt === ".mxweb") {
    // MXWEB 直接读取
    const tempUrl = URL.createObjectURL(file);
    mxcad.openWebFile(tempUrl);
  } else {
    alert("不支持该文件格式，请上传 .dwg, .dxf 或 .mxweb");
  }
  
  // 重置 input value，允许重复选择同一文件
  target.value = "";
};
</script>

关键点说明：

转换接口: http://localhost:3000/uploadfile 是云图开发包自带的演示服务，实际生产环境请替换为您的后端地址。
路径约定: 代码假设转换服务会将结果固定在 /demo/ 目录下，且文件名保持原名仅后缀变为 .mxweb。
API 调用: 无论源文件是什么，最终都统一调用 mxcad.openWebFile(url) 进行渲染。openWebFile 支持更多高级参数，例如控制是否使用工作线程 (isWorkThread)、指定数据加载到内存还是 IndexedDB (fetchAttributes) 等。如需了解完整的参数定义及详细说明，请访问官方文档： McObject.openWebFile API 文档。

2.4 批注功能实现（创建、保存、回显）

1. 创建批注（以审图云线为例）

此功能通过 MxDraw 提供的交互接口，让用户在图上绘制云线并添加文字说明。

typescript

import {
  MxFun,
  MrxDbgUiPrPoint,
  McEdGetPointWorldDrawObject,
  MrxDbgUiPrBaseReturn,
  MxDbRectBoxLeadComment,
} from "mxdraw";

// 绘制云线批注函数
function startCloudMark() {
  const point = new MrxDbgUiPrPoint(); // 获取点交互对象
  const mxDraw = MxFun.getCurrentDraw(); // 获取当前绘图对象
  const worldDrawComment = new McEdGetPointWorldDrawObject(); // 动态绘制辅助对象
  const mxCheckDraw = new MxDbRectBoxLeadComment(); // 云线批注实体对象

  // 设置云线半径（屏幕坐标转文档坐标）
  mxCheckDraw.radius = MxFun.screenCoordLong2Doc(5);
  mxCheckDraw.setLineWidth(3);
  mxCheckDraw.setLineWidthByPixels(true);

  // 第一步：获取起始点
  point.setMessage("\n云线框起始点: ");
  point.go((status) => {
    if (status != MrxDbgUiPrBaseReturn.kOk) return;
    
    mxCheckDraw.point1 = point.value();
    
    // 动态预览：移动鼠标时绘制矩形
    worldDrawComment.setDraw((currentPoint) => {
      mxCheckDraw.point2 = currentPoint;
      worldDrawComment.drawCustomEntity(mxCheckDraw);
    });

    point.setUserDraw(worldDrawComment);
    point.setMessage("\n云线框结束点: ");
    
    // 第二步：获取结束点
    point.go((status) => {
      if (status != MrxDbgUiPrBaseReturn.kOk) return;
      
      mxCheckDraw.point2 = point.value();
      
      // 动态预览：确定文本位置
      worldDrawComment.setDraw((currentPoint) => {
        mxCheckDraw.point3 = currentPoint;
        worldDrawComment.drawCustomEntity(mxCheckDraw);
      });

      // 设置批注文本属性
      mxCheckDraw.text = "审图批注";
      mxCheckDraw.textWidth = MxFun.screenCoordLong2Doc(100);
      mxCheckDraw.textHeight = MxFun.screenCoordLong2Doc(50);
      mxCheckDraw.fixedSize = true;

      if (mxCheckDraw.fixedSize) {
        mxCheckDraw.textHeight = 20;
        mxCheckDraw.textWidth = 130;
      }

      point.setMessage("\n审图标注点: ");
      
      // 第三步：获取文本引出点
      point.go((status) => {
        if (status != MrxDbgUiPrBaseReturn.kOk) return;
        
        mxCheckDraw.point3 = point.value();
        // 将实体添加到图纸数据库
        mxDraw.addMxEntity(mxCheckDraw);
      });
    });
  });
}

绘制效果如下所示：

2. 保存批注数据

使用官方推荐的 saveMxEntityToJson() 方法，将当前图纸上的所有非原生实体（即批注）序列化为 JSON 字符串。本示例暂存至 localStorage 模拟数据库存储。

typescript

import { MxFun } from "mxdraw";

// 保存图纸批注
const saveMarkup = () => {
  const draw = MxFun.getCurrentDraw();
  if (!draw) return;
  
  // 序列化批注数据
  const jsonData = draw.saveMxEntityToJson();
  localStorage.setItem("mx-markup-data", jsonData);
  alert("批注已保存至本地存储");
};

3. 回显批注数据

当用户再次打开图纸时，从存储中读取 JSON 数据，并调用 loadMxEntityFromJson() 还原批注。

typescript

import { MxFun } from "mxdraw";

// 恢复图纸批注
const loadMarkup = () => {
  const draw = MxFun.getCurrentDraw();
  if (!draw) return;

  const jsonData = localStorage.getItem("mx-markup-data");
  if (jsonData) {
    draw.loadMxEntityFromJson(jsonData);
    alert("批注已加载");
  } else {
    alert("未找到保存的批注数据");
  }
};

最佳实践提示：在实际业务中，应将 saveMarkup 生成的 JSON 数据通过 AJAX/Fetch 发送给后端，与图纸 ID 关联存储；loadMarkup 应在图纸加载完成后（监听 onOpenFileComplete 回调）自动从后端拉取数据并执行加载。

2.5 运行验证

启动服务：
- 确保云图转换服务已在 localhost:3000 运行。
- 启动前端项目：npm run dev。
测试流程：
- 预览 MXWEB：点击“打开图纸”，选择 .mxweb 文件 → 图纸秒开。
- 预览 DWG：点击“打开图纸”，选择 .dwg 文件 → 自动上传转换 → 加载转换后的图纸。
- 绘制批注：点击“绘制云线批注”，在图上依次点击起始点、结束点、文字引出点 → 云线绘制成功。
- 保存：点击“保存批注” → 检查浏览器 LocalStorage 是否有 mx-markup-data 键值。
- 回显：刷新页面（清空内存），重新打开同一张图纸 → 点击“加载批注” → 确认云线准确还原。

3. 常见问题与注意事项

路径配置敏感性
- Wasm 文件和字体文件的路径配置必须精确。若控制台出现 404 错误或 Wasm 编译失败，请首先检查 public 目录结构及初始化参数中的 locateFile 和 fontspath 路径字符串是否正确。
跨域隔离策略 (COOP/COEP)
- 较新版本的 MxCAD 利用 SharedArrayBuffer 进行多线程优化以提升性能。若在 Chrome/Edge 中遇到 SharedArrayBuffer is not defined 相关报错，必须在 Web 服务器（或 Vite 配置）的响应头中严格配置：
  - Cross-Origin-Opener-Policy: same-origin
  - Cross-Origin-Embedder-Policy: require-corp
字体缺失处理
- 若图纸文字显示为问号或乱码，通常是因为缺少对应的 SHX 字体文件。请确保开发包中的 fonts 目录已完整部署到项目中，或在后端转换服务中配置字体映射。
大文件性能
- 对于超过 50MB 的超大图纸，建议在加载前进行前端提示。可考虑启用 SDK 中的按需加载功能或简化显示模式（如关闭抗锯齿、隐藏填充图案）以优化渲染帧率。
批注数据管理
- 批注数据是独立于原图存在的。务必在前端或后端建立“图纸 ID - 批注 JSON”的映射关系，避免不同图纸间的批注混淆。

MxCAD APP应用集成

功能示例demo

标注测量

绘图工具

编辑工具

文字工具

其他

入门指南

CAD 功能开发

应用集成

入门实战：基于 MxCAD 与 MxDraw 构建 Web CAD 预览与批注应用 ​

0. 前言 ​

1. 核心架构解析：MxCAD 与 MxDraw 的功能界定 ​

1.1 MxDraw：轻量级前端渲染与批注引擎 ​

1.2 MxCAD：全功能 CAD 业务内核 ​

1.3 协作机制与版本演进 ​

基础与升级的关系 ​

协作模式 ​

2. 构建基础 CAD 项目：图纸预览与批注实战 ​

2.1 环境准备与项目初始化 ​

1. 环境要求 ​

2. 创建或集成项目 ​

3. 安装核心依赖 ​

4. 配置构建工具支持多线程 ​

2.2 创建 Canvas 容器与初始化 MxCAD 引擎 ​

1. 模板结构：Canvas 与文件上传控件 ​

2. 初始化 MxCAD 实例 ​

2.3 打开图纸并预览（关键格式说明） ​

1. 文件选择与处理流程 ​

2. 跨域处理配置 ​

3. 代码实现：打开网络图纸 ​

2.4 批注功能实现（创建、保存、回显） ​

1. 创建批注（以审图云线为例） ​

2. 保存批注数据 ​

3. 回显批注数据 ​

2.5 运行验证 ​

3. 常见问题与注意事项 ​

入门实战：基于 MxCAD 与 MxDraw 构建 Web CAD 预览与批注应用

0. 前言

1. 核心架构解析：MxCAD 与 MxDraw 的功能界定

1.1 MxDraw：轻量级前端渲染与批注引擎

1.2 MxCAD：全功能 CAD 业务内核

1.3 协作机制与版本演进

基础与升级的关系

协作模式

2. 构建基础 CAD 项目：图纸预览与批注实战

2.1 环境准备与项目初始化

1. 环境要求

2. 创建或集成项目

3. 安装核心依赖

4. 配置构建工具支持多线程

2.2 创建 Canvas 容器与初始化 MxCAD 引擎

1. 模板结构：Canvas 与文件上传控件

2. 初始化 MxCAD 实例

2.3 打开图纸并预览（关键格式说明）

1. 文件选择与处理流程

2. 跨域处理配置

3. 代码实现：打开网络图纸

2.4 批注功能实现（创建、保存、回显）

1. 创建批注（以审图云线为例）

2. 保存批注数据

3. 回显批注数据

2.5 运行验证

3. 常见问题与注意事项